Collection of Tools & Utilities

home *** CD-ROM | disk | FTP | other *** search

/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / batchut / batman.zip / BATMAN.DOC next >

Wrap

Text File | 1988-07-20 | 25.0 KB | 886 lines

BATMAN (BATch job MANager) A Tool For Adding Pizazz To Batch Files Version 1.1 Presented to the public by: GS Communications PO Box 5962 Titusville, FL 32783 First, the copyright and disclaimers; * BATMAN is the property of GS Communications with authoring rights by Guy Smith. GS Communications reserves all rights and privileges afforded by copyright statues. * BATMAN is released to the public as a Shareware offering. This means you may use the program as you like with no restrictions. The author asks that you make a one dollar contribution if you receive any benefit from the program at all. * Business concerns, and this includes sole proprietorships, partnerships, corporations, nonprofit organizations, government agencies, and cartels must pay a one time, five dollar site licensing fee. * GS Communications offers a cash reward for evidence of business concerns that use BATMAN, or any other software produced by GS Communications, without paying the requisite fee. * GS Communications and Guy Smith waive all responsibility for the usefulness of the product or any damage it may inadvertently cause (though it is a clean as clean can be). 2 Just What In The Heck Is BATMAN Anyhow: BATMAN is a comic book character that achieved zenith popularity during the run of a network television show of the same name which aired during the 1960's. But that's irrelevant. This program, BATMAN, is a tool for bringing a little life an pizazz to your MS-DOS batch files. The program allows you to do a number of tricks which are either 1) impossible to with conventual MS-DOS commands 2) require cryptic ASNI code to produce or 3) would otherwise require a bunch of separate utilities I'll get into more detail in a moment. For now we can say that BATMAN will allow you to; * Make the speaker beep for any number of times, at any tone and with any duration of tone and gap between the tones * Play 'canned' songs and interesting sound effects * Switch to any video mode (this saves floppy disc users from having to have the MODE program on every disc). Support is included for 43 lines on EGA systems and 50 lines on VGAs. * Get responses from users and thus allows the batch file to react to their answers * Set foreground and background colors for text * Write text at any position on the screen * Solicit "Yes or no" response with many variations. * Draw boxes with border for putting detail text into * And many other stunts 3 NEW AND IMPROVED: I have made a number of improvement since 1.0. Briefly they are; 1) The YORN command doesn't make a mess of the screen any more. Originally it produced an error message which, if the user made too many mistakes, would cause the screen to scroll away. Now an error window opens, tells the user to try a "yes or no" type answer, and then disappears with the first keystroke. I have used a set text attribute for the error box (red background, black foreground), which may interfere with your choice. Later I'll write in a test of colors and change them dynamically. 2) New commands which clear the screen (an oversight in the first version), draw a box and report the current video mode. 3) New sound effects/songs up to five from three (there should be more, but I've been busy). 4) Process BATMAN commands from a file for faster response. Sound good? Well flip the page and I'll start describing the program. 4 How Do You Use BATMAN: Well, first you use the Bat Telephone, dial 1-800-BAT-CAVE . . . I'm sorry about these silly outburst, but this is a silly day. Besides, the name of the program makes for obvious jokes. To run BATMAN, simply type BATMAN followed by one of the supported parameters. Since BATMAN is designed for use in batch files, you will probably want to experiment by building your own. In this package, there is a batch file named DEMO.BAT which shows off some of the features of BATMAN. Each of the parameters is a command name which can be abbreviated to three letters (it was four in version 1.0, but I found a good reason to decrease the character count). For example, the following two commands function identically; BATMAN VIDEOMODE(CO80) BATMAN VIDE(CO80) You can use more than three letters if you like. The only restriction is that the first four characters must match a command name exactly. You could say; BATMAN VIDEO_MODE_HAS_POWER(CO80) without making the program bomb. As you may note, the VIDEO command has a parameter all its own, which is encased in parenthesis. Most commands have such a parameters, some have several, and a few have none at all. Don't let this bother you. If you ever forget how to structure a parameter, just type in BATMAN with no commands (or with the HELP command) and a short list of commands and parameters will be displayed. You can combine commands on a single line. This is advised since each command line that calls BATMAN causes the computer to hunt down the program, allocate memory, load and initialize the program, and more time consuming processes. This new version also allows you to use an entire file of BATMAN commands which makes the process even faster. The only time you need to exit BATMAN is when a batch file decision is required (i.e. the IF statement). Finally, I suggest you keep BATMAN in the first directory in your path statement (this section really only applies to hard disc users, so floppy folks can read on). My \UTIL directory is first in the path list and I keep BATMAN at the top of the directory (there are a number of utilities that allow you to shuffle the order in which files appear in a subdirectory). This speeds up batch file execution greatly and saves some wear and tear on the drive. 5 Some much for the basics. Flip the page and we'll learn about each of the parameters. BEEP(num,dur,frq,gap) This command produces beeps of a specific tone, duration and delay (i.e. no sound at all) between beeps. num: The number of beeps you want to hear. dur: The length of the beep in milliseconds. frq: The frequency, or tone of the beep. gap: The delay between beeps. Use numbers only. Using character will produce an error message (try it, you'll be surprised). You can use negative numbers, but the program ignores the negative value, and uses the absolute value. The commas are the only delimiters allowed in BATMAN. The command; BATMAN BEEP(3,500,440,250) produces three beeps. Each beep is 1/2 second long and is played at 440 Hz (or middle A). Silence is heard for 1/4 second between each beep. I decided to leave the parameters as numbers instead of devising some coding scheme. This saves program size and processing speed and makes BATMAN run faster. Since BATMAN may be used many times, it is essential to keep it as tight as possible. For the convenience of those with a musical background, the following chart shows the best approximate value for frq to use; OCTAVE NOTE NUMBER │ OCTAVE NOTE NUMBER ══════════════════════════════│══════════════════════════════ 0 A 27 │ 4 F 349 0 B 31 │ 4 G 392 1 C 33 │ 4 A 440 1 D 37 │ 4 B 494 1 E 41 │ 5 C 523 1 F 44 │ 5 D 587 1 G 49 │ 5 E 659 1 A 55 │ 5 F 698 1 B 62 │ 5 G 784 2 C 65 │ 5 A 880 2 D 73 │ 5 B 988 6 2 E 82 │ 6 C 1046 2 F 87 │ 6 D 1175 2 G 98 │ 6 E 1318 2 A 110 │ 6 F 1397 2 B 123 │ 6 G 1568 3 C 131 │ 6 A 1760 3 D 147 │ 6 B 1975 3 E 165 │ 7 C 2093 3 F 175 │ 7 D 2349 3 G 196 │ 7 E 2637 3 A 220 │ 7 F 2794 3 B 247 │ 7 G 3136 4 C (mid) 262 │ 7 A 3520 4 D 294 │ 7 B 3951 4 E 329 │ 8 C 4186 I'll update this chart in future release to show the values for sharps and flats. For now, your best bet is to pick a number between the two surrounding values (i.e. 1st octave A# should be about 58). As I noted before, these are the closet approximate value for the frequencies possible. They are close enough that the untrained ear won't notice the difference. For duration and gap, I offer the following; VALUE │ BEAT ═════════│═══════════════════════ 1000 │ Hole note 500 │ Half note 250 │ Quarter note 125 │ Eighth note 66 │ Sixteenth note 31 │ Thirty second note PAUSE(sec) Causes the batch file to do nothing. This is important. It allows users to read messages, or admire your beautiful display. sec: Time to delay in seconds. This measure is approximate (i.e. it is not exactly a second, but a touch more). VIDEO(mode) Changes the display mode used by your video adapters. Since MS- DOS can support both a color and monochrome monitor in a single computer, this command is handy for adjusting this value (you can also use the MODE program supplied on your MS-DOS disc, but that's just one more file to keep track of). Additionally, you 7 can adjust the line densities of EGA and VGA monitors. mode: Text which describes what video mode to use. The following list contains the only valid parameters; CO80: Set video for a color adapter and 80 characters across the screen. BW80: Same as above, but in Black and White. CO40: 40 column video in color. BW40: 40 column video in Black and White. MONO: Switches to a monochrome adapter. EGA43: Switches an EGA system to 43 lines of text and 80 columns. VGA50: Switches a VGA system to 50 lines of text and 80 columns. Don't worry too much about choosing the wrong parameter. MS-DOS is forgiving on this point and won't let you do the impossible (like switch to MONO if you do not have a monochrome adapter installed). MODE Reports what mode the CRT is in. This is very handy if you try to create a batch file set which works differently with any monitor/card combination (if you do this, you are a prime masochists). The values reported by MODE are returned in the errorlevel DOS variable, and can have the following values; 0: Black and white in 40 column mode 1: Color in 40 column mode 2: Black and white in 80 column mode 3: Color in 80 column mode 7: Monochrome monitor, 80 columns SONG(num) Plays a tune or sound effect already stored in BATMAN (I am working on the theme song from the old Batman program). At present, there are only three tunes stored. num: A number from 1 to 4. 1 - A rising pitch which lasts for a few seconds 2 - A laser blast 8 3 - A short tune akin to "Irish Eyes" 4 - A butchery of the interlude in Jethro Tulls "Mother England Reverie" 5 - A note quite right version of the "Close Encounters" contact tune I have a goal of adding one more tune for every new feature added to BATMAN. In time, I suspect the tune will exceed 15 or 20. If you want something else, try experimenting with the BEEP command and put as many BEEPs on a command line as possible. ERRORCODE This command takes a number from the user and uses it as the exit code. This code, MS-DOS environment variable ERRORLEVEL, can then be used to branch elsewhere in the batch file. There is no parameter for this command. The best use for ERRORCODE would be in constructing a menu. Here is an example batch file of a simple menu system; BATMAN WRITE( 1 ........ Lotus 1-2-3) BATMAN WRITE( 2 ........ Space Invaders) BATMAN WRITE( 3 ........ PC Paintbrush) BATMAN WRITE( Enter a number:) ERRORCODE IF ERRORLEVEL 1 GOTO LOTUS IF ERRORLEVEL 2 GOTO INVADERS IF ERRORLEVEL 3 GOTO PAINT ... Actually, there is another step involved, but this shows the intent. Be careful not to use ERRORCODE and YORN commands on the same BATMAN line. Both set ERRORLEVEL and using both will cause the first to be unusable. INFO Displays information about BATMAN, myself and where to send money and bug reports. FOREGROUND(fcolor,BLINK) Sets the foreground text color. All text sent to the screen after this command is processed will be displayed using the color specified. An optional parameter, BLINK, will cause the characters to blink on and off while they are on the screen. 9 fcolor: One of 16 foreground colors. They are; BLUE LIGHTBLUE GREEN LIGHTGREEN CYAN LIGHTCYAN RED LIGHTRED MAGENTA LIGHTMAGENTA DARKGRAY LIGHTGRAY BROWN YELLOW BLINK: If blinking characters are desired, use the key word BLINK. No other value will do. Use the names exactly as they appear in this chart. It doesn't matter if they are upper case, lower case or mixed. Just don't separate the word roots. BACKGROUND(bcolor) Sets the background color, the color behind the actual characters to be printed. bcolor: Only eight colors are available for the background; BLACK BLUE GREEN CYAN RED MAGENTA BROWN LIGHTGRAY Please note that if you select BLACK as your foreground color, you better select a new background color, and one other than black. Otherwise, all your text will simply never show up. HELP Displays a short help screen, the same as if you ran BATMAN without any commands. There are no parameters for this command. WRITE(text) Displays text on the video screen. Text is limited only to the length of the command line in your batch file and one character. text: The text you want displayed. DO NOT USE PARENTHESIS AS PART OF YOUR TEXT!!!!! There is a technical reason why you can not use a right paren ")" in this command (for the technically minded, read TECHNICAL 10 ISSUES at the end of this document). The text will be drawn at the current cursor location. The cursor will remain at the end of the text line. This allows you to use commands ERRORCODE and YORN to get responses from users, and have the responses displayed at the correct position on the screen (not on the next line or some silliness like that). GOTO(x,y) Causes the video cursor to move to the defined row and column. This is very handy for making dazzling displays with banners, marked fields and the like. x: The column you want to start in. Normally a position 1 through 80, except when your are in 40 column mode. y: The row to move to, anywhere from 1 to 50 depending on video adapters and mode settings. Normally 1 through 25. Use numbers only. Anything else causes BATMAN to hurl insults in your direction (then again, so does any truly invalid parameter). If you use a negative number, BATMAN ignores the negative sign and uses the absolute value. Numbers greater than the limits of your video screen will be ignored. YORN Gets either a 'yes' or 'no' response from the user. The nature of the response can be a number of different variations. A value of either zero or one is returned to ERRORLEVEL when the program finishes. Zero means the user specified 'no' while a one specifies 'yes'. Valid 'yes' answers: YES, AYE, OK, OKAY, SI, OUI, DA, YEP, FINE, 1, Y Valid 'no' answers: NO, NINE, NYET, NEGATIVE, NAY, NIX, N FILE(filename) Processes BATMAN commands in a file. Commands are the same and can have the BATMAN token on the front of the line (this makes for easy switching from batch file line mode to command file mode). filename: the name of the file containing the commands to process. You must specify the entire file name, including path (if other than current) and extension. I suggest using the 11 extension BM for BATMAN command files (see DEMO.BAT for an example). No default file name extension is used. BLANK Clears the screen using the current text attributes. I included this to avoid having to exit BATMAN just to clear the screen (You may also use the command CLS, just like in DOS. This helps moving an old BATMAN batch file to command file format). If you specify a text attribute before using blank (say BACKGROUND(RED)) then the entire screen receives the attribute. BOX(x,y,height,width,horiz,vert) Draws a box with border on screen using the current text attribute. I included this since I included my windowing routines to handle BATMAN errors in other routines. This is a quick way to put up fancy headers and such. x,y: The screen x and y coordinates with the upper left corner being 1,1. height: The number of total line tall the box will be INCLUDING the top and bottom frame lines. width: Same as above except how wide the box is. horiz: The line type for horizontal lines. Must be either SINGLE or DOUBLE. This will produce a line that is either a "─" or a "═". vert: Same as above except for vertical lines. Produces either a "│" or a "║". In all cases the lines convert to proper joining corners to match the lines. The following BATMAN line produces a red box, with black letters and double lines all the way around in the center of your screen. Try it; BATMAN foreground(black) background(red) box(10,10,60,5,double,double) I welcome suggestions for more. Answers need not be in upper case. They can be upper, lower or mixed case. Giving a response other that one listed will tell the use that their answer is ambiguous and to please enter it again. For now the message is not very pretty and will cause screen roll if repeated. I'll fix this in a later version. The fix will employ an error window, color and a return of the cursor to it's original position. 12 13 PROBLEMS AND FUNDS: Please report any problems you discover with BATMAN. This will help with making the system batter in later releases. Anyone who sends in a problem report and a blank disc (with return postage) will get the latest release and bug fix free (if you are going to the trouble to send in a report, don't forget the one dollar Shareware fee). Send all correspondence to: GS Communications PO Box 5962 Titusville, FL 32783 or Guy Smith Compuserve # 72057,655 or Wizard ! Compusult BBS (407) 729-0935 COMING ATTRACTIONS: I am already looking forward to version 1.2 of BATMAN. No release date will be announced, but I suspect it won't be a month or two following this. I would like any and all suggestions you may offer. Credit for outstanding suggestions will appear in the documentation. I am considering adding the following features; * The ability to SET environment variable with user response. This would allow more control in batch files and allow responses like 'A', 'B' or 'DONT-CARE' instead of just numbers. * Large letters. This would allow you to have a line of text appear in letters larger than normal. May also consider several different text styles, like Shadow or Old English. * Support DOS commands which would normally require another program. Mode was eliminated in this release (as far as video was concerned). What else is useful, but requires a separate program? TECHNICAL ISSUES BATMAN is coded entirely in Turbo Pascal 4.0. If something doesn't work, then it's Borland's fault. I may toy around with 14 assembly language speed-em-ups later, but for now it's plain vanilla. The driving goals behind BATMAN were to keep the program small and fast while making it easy to use. These goals are always at odds with one another, so some compromises had to be made. The worst one was the use of regular integers for parameters in the BEEP command. It would have been elegant to specify tones as musical scales (i.e. a symbol like 3C# for 'third octave C sharp') and to have the durations and gaps in beats (say '1' for a whole note and '4' for a quarter note, etc). However, lean and mean beats fancy any day. Source code is available upon request. Send one dollar, a blank disc and return postage in a disc mailing envelope to; GS Communication PO Box 5962 Titusville, FL 32783 You will get the souce code, documentation and object code for the latest version of BATMAN. I welcome any criticism about coding style and efficiency you care to offer. 15